home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-01
/
proto212.zip
/
EXAMPLE.ZIP
/
DOCUMENT.EXM
next >
Wrap
Text File
|
1992-01-24
|
4KB
|
78 lines
The file example.zip holds several files. We will try to
present what the documentation tools are. In this text, the
word documentation refers to whatever tools help programmers
understand and use software libraries. We are not talking
about user documentation.
Providing a reliable documentation on a software system
is not easy. Most methodologies based on system too far
away from the source code won't work.
Reliable documentation on a system helps code reusability.
Here is, we believe, the most important things to do for code
reuse to happen.
A) Software component must be easy to locate. Programmers
need index, summary, reference guides ... If a component
exists but is not easy to locate, it will be duplicated.
B) Software component must be easy to understand.
Each function of a system must be documented, simply and
that documentation must be near the code itself.
C) The code must work well !
The Solucorp Programmer's Toolkit start from a simple principle.
Reliable documentation for a software component (function) is
in the source code, immediatly near the declaration part of the
component. If this documentation is not reliable, then nothing
will ever be.
The guidelines are simple. The first line of comments before a
function declaration is a short description of the function
action. All following comments before the declaration should
tell explicitly what the function does, when a programmer must
use it, what would make this function better, what values are
returned, and so on.
The source files (source*.c) provided show a sample system with
very short documentation. In the provided makefile, a target
"doc" at the end, shows which commands are used to update the
documentation kit.
From the source file, proto (the prototype extractor) gets
the prototypes and surrounding comments. The file xsys.nap
is produced.
Naperm format three files from xsys.nap.
xsys.nas : All functions are presented with the short documentation.
xsys.nai : This is a permutted index of the file xsys.nas.
xsys.nah : This is a log of all revisions made to project xsys.
It shows when functions has been added, modified or
deleted from system xsys.
Those three files are good to spot a function when you have
at least a small experience with system xsys. If you are
new to xsys, and the system has over a hundred functions, you
need something else. You need a general document that introduces
xsys and present function is an organised way. This kind of
document is difficult to produce. It is generally huge. It
is often inacurate. For all this, it is also never read.
There is a way out. If you have acurate documentation in
the source files for each function, then there is a way
to create this document without too much pain. The file
xsys.doc is the layout of the reference manual of system
xsys. It contains simple introduction, a general outline of
the system, and simple classification of the function of the
system.
From xsys.doc and xsys.nap, the file xsys.ref is produced.
This file is the reference manual. It is always up to date.
Nadoc is the utility that produced that. It will spot all
functions not classified in xsys.doc. It will also
tell about functions that do not exist anymore.